18.2. Reporting¶
Starting with LinOTP 2.9 a new reporting API was introduced. It can be used to query information about the number of tokens. This can be useful for accounting in multitenancy environments or statistical purpose.
The comprehensive API documentation can be found here:
https://www.linotp.org/doc/api/linotp.controllers.reporting.html
The basic API call is:
https://<LINOTP>/reporting/<ReportingController>?session=SESSIONCOOKIE[&PARAM1][&PARAM2][..]
The available controllers are:
show- displays historical count data
maximum- displays highest values counted
delete_all- clean the counter database
delete_before- delete all values in the counter database recorded before a defined date
Tip
Detailed information about the handling of the session cookie can be found at System Controller
18.2.1. Prerequisites¶
The reporting API can be accessed by the token managers. The available queries have to be configured before via policies as described in Reporting Policies.
Tip
After adding new states to be recorded in the policies the next count will be performed after an event was triggered potentially changing the counted value. So for example if a new token is enrolled the counters are recalculated and can be queried.
18.2.2. Perform Queries¶
18.2.2.1. show¶
Displays the token counters recorded over time. The output can be filtered regarding the token states and the realms.
https://<LINOTP>/reporting/show?session=SESSIONCOOKIE[&PARAM1][&PARAM2][..]
Available parameters:
realms[optional]- Limit the counter output to the given realms.
status[optional]- Limit the counter output to tokens with of certain states.
Explanation of the available token states:
active- counts only active tokens
inactive- counts only deactivated tokens
assigned- counts only tokens assigned to users
unassigned- counts only tokens which are not assigned to any user
active&assigned- counts tokens which are activ and assigned to an user
active&unassigned- counts active tokens which are not assigned to any user
inactive&assigned- counts disabled tokens assigned to users
inactive&unassigned- counts disabled tokens which are not assigned to any user
Tip
Please make sure to use exactly the same token states for the queries as defined in the reporting policies (Reporting Policies)
- Displays all available historical numbers of all tokens of all states
https://<LINOTP>/reporting/show?session=SESSIONCOOKIE
Example
https://linotp.example.net/reporting/show?session=45e939b02[...]
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": {
"resultset": {
"page": 1,
"pages": 1,
"pagesize": 30,
"report_rows": 30
},
"data": [
{
"count": 132,
"realm": "realm1",
"description": "",
"timestamp": "2016-07-25 13:27:47",
"detail": "",
"value": "",
"session": "",
"parameter": "active",
"event": "token_tokenrealm"
},
{
"count": 150,
"realm": "realm1",
"description": "",
"timestamp": "2016-07-25 13:27:47",
"detail": "",
"value": "",
"session": "",
"parameter": "total",
"event": "token_tokenrealm"
},
[...]
- Display token counts for certain realms
https://<LINOTP>/reporting/show?session=SESSIONCOOKIE&realms=REALMA,REALMB
Example
Show token count numbers for ‘realm1’ and ‘realm2’:
https://linotp.example.net/reporting/show?session=45e939b02[...]&realms=realm1,realm2
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": {
"resultset": {
"page": 1,
"pages": 1,
"pagesize": 30,
"report_rows": 30
},
"data": [
{
"count": 132,
"realm": "realm1",
"description": "",
"timestamp": "2016-07-25 13:27:47",
"detail": "",
"value": "",
"session": "",
"parameter": "active",
"event": "token_tokenrealm"
},
{
"count": 150,
"realm": "realm1",
"description": "",
"timestamp": "2016-07-25 13:27:47",
"detail": "",
"value": "",
"session": "",
"parameter": "total",
"event": "token_tokenrealm"
},
[...]
{
"count": 300,
"realm": "realm2",
"description": "",
"timestamp": "2016-07-25 13:27:54",
"detail": "",
"value": "",
"session": "",
"parameter": "active",
"event": "token_tokenrealm"
},
[...]
}
- Display token count numbers for certain states
https://<LINOTP>/reporting/show?session=SESSIONCOOKIE&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]
Example
Show count numbers for unassigned active tokens:
https://linotp.example.net/reporting/show?session=45e939b02[...]&status=unassigned%26active
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": {
"resultset": {
"page": 1,
"pages": 1,
"pagesize": 6,
"report_rows": 6
},
"data": [
{
"count": 11,
"realm": "realm1",
"description": "",
"timestamp": "2016-07-26 11:37:58",
"detail": "",
"value": "",
"session": "",
"parameter": "unassigned&active",
"event": "token_enable"
},
{
"count": 12,
"realm": "realm1",
"description": "",
"timestamp": "2016-07-26 13:00:10",
"detail": "",
"value": "",
"session": "",
"parameter": "unassigned&active",
"event": "token_init"
},
[..]
}
- Display count numbers for tokens of a certain states from particular realms
https://<LINOTP>/reporting/show?session=SESSIONCOOKIE&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]
Example
Show count numbers for unassigned+active and unassigned+inactive tokens from ‘realm1’:
https://linotp.example.net/reporting/show?session=45e939b02[...]&status=unassigned%26active,unassigned%26inactive&realms=realm1
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": {
"resultset": {
"page": 1,
"pages": 1,
"pagesize": 12,
"report_rows": 12
},
"data": [
{
"count": 0,
"realm": "realm1",
"description": "",
"timestamp": "2016-07-26 11:37:58",
"detail": "",
"value": "",
"session": "",
"parameter": "unassigned&inactive",
"event": "token_enable"
},
{
"count": 8,
"realm": "realm1",
"description": "",
"timestamp": "2016-07-26 11:37:58",
"detail": "",
"value": "",
"session": "",
"parameter": "unassigned&active",
"event": "token_enable"
},
{
"count": 0,
"realm": "realm1",
"description": "",
"timestamp": "2016-07-26 13:00:10",
"detail": "",
"value": "",
"session": "",
"parameter": "unassigned&inactive",
"event": "token_init"
},
[..]
}
18.2.2.2. maximum¶
Display the highest number counter for token of a certain state in realms.
https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE[&realms=REALMA,REALMB,...][&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]]
Available parameters:
status [optional]
realms [optional]
- Show total number of tokens
https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE
Example
Show highest numbers of total tokens counted for all realms:
https://linotp.example.net/reporting/maximum?session=45e939b02[...]
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": {
"realm1": {
"total": 270
},
"realm2": {
"total": 178
}
}
},
"id": 1
}
- Show number of tokens of certain states
https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE&status=STATEA[%26STATEB][,STATEC[%26STATED]]
Example
Show highest numbers counted of inactive tokens for all realms:
https://linotp.example.net/reporting/maximum?session=45e939b02[...]&status=inactive
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": {
"realm1": {
"inactive": 25
},
"realm2": {
"inactive": 13
}
}
},
"id": 1
}
- Show number of tokens of certain states from specific realms
https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE&realms=REALMA[,REALMB][..]status=STATEA[%26STATEB][,STATEC[%26STATED]][..]
Example
Show highest numbers counted of unassigned or inactive tokens for ‘realm1’:
https://linotp.example.net/reporting/maximum?session=45e939b02[...]&status=inactive,unassigned&realms=realm1
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": {
"realm1": {
"unassigned": 15,
"inactive": 25
}
}
},
"id": 1
}
18.2.2.3. delete_all¶
Delete all counters from database.
https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all[&realms=REALMA[,REALMB][..]]
[&status=STATEA[%26STATEB][,STATEC[%26STATED]][..]]
Available parameters:
status [optional]
realms [optional]
- Delete all count data
https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all
Example
https://linotp.example.net/reporting/delete_all?session=45e939b02[...]
{
"version": "LinOTP 2.9rc2",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": 586
},
"id": 1
}
- Delete token counter of selected realms
https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all&realms=REALMA[,REALMB][..]
Example
Delete all tokens counter from realm1:
https://linotp.example.net/reporting/delete_all?session=45e939b02[...]&realms=realm1
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": 432
},
"id": 1
}
- Delete token counter for selected states
https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all&status=STATEA[%26STATEB][,STATEC[%26STATED][..]
Example
Delete all tokens counter of the state inactive or disabled:
https://linotp.example.net/reporting/delete_all?session=45e939b02[...]&status=inactive,disable
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": 18
},
"id": 1
}
18.2.2.4. delete_before¶
Delete entries from the database before a given date. The removal can be optionally selective regarding the realm and the token states.
https://<LINOTP>/reporting/delete_before?session=SESSIONCOOKIE&date=YYYY-MM-DD[&realms=REALMA,REALMB,...]
[&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]]
Available parameters:
date- the date before counters are deleted in format YYYY-MM-DD
status [optional]
realms [optional]
Example
Remove all count data recorded before 2016-07-22:
https://linotp.example.net/reporting/delete_before?session=45e939b02[...]&date=2016-07-22
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": 157
},
"id": 1
}
Example
Remove count data for all active token from realm1 recorded before 2016-07-26:
https://linotp.example.net/reporting/delete_before?session=45e939b02[...]&status=active&realms=realm1&date=2016-07-26
{
"version": "LinOTP 2.9",
"jsonrpc": "2.0802",
"result": {
"status": true,
"value": 68
},
"id": 1
}